home *** CD-ROM | disk | FTP | other *** search
/ InfoMagic Internet Tools 1993 July / Internet Tools.iso / RockRidge / security / xinetd / sio.1.5.6 / README < prev    next >
Encoding:
Text File  |  1992-12-09  |  6.0 KB  |  159 lines
  1. ======================================================================
  2. NOTE: I use vi with a tabstop value of 3. Using the same tabstop
  3.         value will make the text/code look properly indented.
  4. ======================================================================
  5.  
  6.  
  7. What is SIO ?
  8.  
  9. SIO is a library that provides _stream_ I/O which is what most Unix
  10. programs do. As such it is a competitor to stdio.
  11.  
  12.  
  13. Why you would care to use it ?
  14.  
  15. a. It is a little faster than stdio
  16. b. It provides an easier-to-use interface (personal opinion)
  17. c. It is capable of using memory mapping for reading files if the OS 
  18.     supports it.
  19. d. If you have a program that uses read(2)/write(2) it is trivial
  20.    to convert it to use SIO (just replace read with Sread and 
  21.    write with Swrite)
  22. e. You get source
  23.  
  24.  
  25.  
  26. How to install the Stream I/O (SIO) library
  27.  
  28. There are 3 parts in installing SIO: setting up a sioconfig.h file,
  29. setting up the Makefile and testing SIO.
  30.  
  31.  
  32. 1. Setting up sioconfig.h
  33.  
  34. The OS specific parts of SIO have been placed in the sioconfig.h file.
  35. This file is a link to the actual configuration file in the Config 
  36. directory. Configuration files for the following OS's are available:
  37.  
  38. SunOS 4.x, Ultrix 4.[12], UMIPS-BSD (BSD 4.3 derivative).
  39.  
  40. Currently the Makefile will create the sioconfig.h link correctly
  41. if you use one of the above OS's, but you may want to disable
  42. that Makefile target and create the link manually (this is recommended).
  43. If there is no configuration file for your OS, you can create one by
  44. using one of the existing ones as a template. Also, make sure you
  45. disable the sioconfig.h target in the Makefile and create the link
  46. manually.
  47. Here is what needs to be defined in sioconfig.h:
  48.  
  49.  
  50. 1.1. Memory mapping
  51.  
  52. If your OS supports memory mapping of regular files and you want to 
  53. use that option then define MEMORY_MAP. If you define MEMORY_MAP
  54. you will also need to define the macros SIO_MMAP, SIO_MUNMAP and 
  55. SIO_MNEED. Check the other configuration files for the arguments of 
  56. these macros.
  57. SIO_MNEED informs the OS about a part of the address space that 
  58. will be needed shortly. Its existence is not mandatory; if your OS
  59. does not support it, define it like this:
  60.     #define SIO_MNEED( addr, len )            /* NOTHING */
  61.  
  62.  
  63. 1.2. Finalization function
  64.  
  65. The purpose of a finalization function is to do work after your
  66. program has called exit(3). In the case of SIO, this means flushing
  67. the SIO output buffers.
  68. If your OS supports the installation of finalization functions you
  69. should define HAS_FINALIZATION_FUNCTION. Then you must define the
  70. macros SIO_FINALIZE and SIO_DEFINE_FIN. SIO_FINALIZE attempts
  71. to install a finalization function and returns TRUE if successful, FALSE
  72. if unsuccessful. SIO_DEFINE_FIN defines the finalization function
  73. (the reason for this macro is that different systems pass different
  74. number/type of arguments to the finalization function; the SIO finalization
  75. function does not use any arguments). Check the other configuration
  76. files for examples of how to define these macros.
  77.  
  78.  
  79. 1.3. General flags
  80.  
  81. The HAS_MEMOPS flag should be defined if your OS supports the mem* functions
  82. (memcpy etc). If not, then you can define HAS_BCOPY if your OS supports bcopy.
  83. At most one of HAS_MEMOPS, HAS_BCOPY should be defined.
  84. You should define the flag HAS_ISATTY if the function isatty exists in
  85. your C library. This library identifies if a desciptor refers to a
  86. terminal.
  87. You must define N_SIO_DESCRIPTORS to be equal to the maximum number of file
  88. descriptors per process supported by your OS.
  89.  
  90.  
  91. 1.4. Sprint constants
  92.  
  93. These are constants that affect the Sprint function:
  94. SMALLEST_INT is the smallest (negative) integer that fits in a machine word.
  95. S_SMALLEST_INT is that integer in string form (without the '-' sign).
  96. S_SMALLEST_INT_LEN is the length of that string.
  97. You should also define LONG_IS_BIGGER if sizeof(long) > sizeof(int).
  98. In that case you also need to write functions to
  99.     a) convert a long to a string in decimal notation (similar to
  100.         the function conv_10)
  101.     b) convert a long to a string in octal or hexadecimal notation 
  102.         (similar to the function conv_p2)
  103.  
  104. Currently the constants are set for a 32-bit 2's complement machine.
  105.  
  106.  
  107. 2. The SIO Makefile
  108.  
  109. The Makefile has a header that explains what the Makefile can do.
  110. The only flag that you can define is -DDEBUG which enables 
  111. assertions in the SIO code (if an assertion fails, the program is 
  112. terminated with an error message that lists the SIO file and line 
  113. number where the error occured).
  114. A simple 'make' command creates libsio.a in the current directory.
  115. If you want to install SIO at some other point of the directory
  116. tree use 'make install'. That will cause the following:
  117.  
  118. a) libsio.a will be moved to LIBDIR
  119. b) the necessary SIO header files will be copied to INCLUDEDIR
  120. c) the SIO man pages will be copied to MANDIR
  121.  
  122. LIBDIR, INCLUDEDIR, and MANDIR are Makefile variables that you must
  123. define.
  124.  
  125.  
  126. 3. Testing SIO
  127.  
  128. After you have successfully compiled SIO, you can use the programs
  129. in the suite/ directory to test all SIO functions.
  130. Testing should be done before installing the library.
  131. The script testlib does everything; just type:
  132.  
  133.     testlib all
  134.  
  135. The script sprint_test (invoked by testlib) tests Sprint by using a variety 
  136. of formats and comparing its output with that of an ANSI-compatible printf.
  137. On Ultrix systems this test fails since printf is not ANSI-compatible.
  138. You can test the rest of the SIO functions by typing:
  139.  
  140.     testlib all Sprint
  141.  
  142. (anything after the 'all' argument is interpreted as a function that
  143. should not be tested)
  144.  
  145.  
  146.  
  147. Epilogue
  148.  
  149. Feel free to modify SIO to suit your needs. Please let me know of
  150. any bugs you find.
  151. If you want to distribute your patches, please read the COPYRIGHT file.
  152. It basically says that you are free to redistribute as long as you make 
  153. sure that your modifications are identifiable. In order to achieve this
  154. I have reserved the first 3 components of the version number (e.g. 1.4.0)
  155. and you can identify your mods by appending another component to that 
  156. version number. Also, you take full responsibility for any bugs in
  157. the code (not just your code; the whole thing).
  158.  
  159.